<!DOCTYPE html>
<html lang="en">
<head prefix="og: http://ogp.me/ns#">
  <meta charset="utf-8">
  <title>Templates | Hexo</title>
  <meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <!-- Canonical links -->
  <link rel="canonical" href="https://hexo.io/docs/templates.html">
  <!-- Alternative links -->
  
    
      <link rel="alternative" hreflang="en" href="https://hexo.io/docs/templates.html">
    
      <link rel="alternative" hreflang="zh-tw" href="https://hexo.io/zh-tw/docs/templates.html">
    
      <link rel="alternative" hreflang="zh-cn" href="https://hexo.io/zh-cn/docs/templates.html">
    
      <link rel="alternative" hreflang="ru" href="https://hexo.io/ru/docs/templates.html">
    
      <link rel="alternative" hreflang="ko" href="https://hexo.io/ko/docs/templates.html">
    
  
  <!-- Icon -->
  <link rel="apple-touch-icon" sizes="57x57" href="/icon/apple-touch-icon-57x57.png">
  <link rel="apple-touch-icon" sizes="114x114" href="/icon/apple-touch-icon-114x114.png">
  <link rel="apple-touch-icon" sizes="72x72" href="/icon/apple-touch-icon-72x72.png">
  <link rel="apple-touch-icon" sizes="144x144" href="/icon/apple-touch-icon-144x144.png">
  <link rel="apple-touch-icon" sizes="60x60" href="/icon/apple-touch-icon-60x60.png">
  <link rel="apple-touch-icon" sizes="120x120" href="/icon/apple-touch-icon-120x120.png">
  <link rel="apple-touch-icon" sizes="76x76" href="/icon/apple-touch-icon-76x76.png">
  <link rel="apple-touch-icon" sizes="152x152" href="/icon/apple-touch-icon-152x152.png">
  <link rel="icon" type="image/png" href="/icon/favicon-196x196.png" sizes="196x196">
  <link rel="icon" type="image/png" href="/icon/favicon-160x160.png" sizes="160x160">
  <link rel="icon" type="image/png" href="/icon/favicon-96x96.png" sizes="96x96">
  <link rel="icon" type="image/png" href="/icon/favicon-16x16.png" sizes="16x16">
  <link rel="icon" type="image/png" href="/icon/favicon-32x32.png" sizes="32x32">
  <meta name="msapplication-TileColor" content="#2f83cd">
  <meta name="msapplication-TileImage" content="/icon/mstile-144x144.png">
  <!-- CSS -->
  <!-- build:css build/css/navy.css -->
  <link rel="stylesheet" href="/css/navy.css">
  <!-- endbuild -->
  <link href="https://fonts.googleapis.com/css?family=Lato:300,400,700" rel="stylesheet" type="text/css">
  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css">
  <!-- RSS -->
  <link rel="alternate" href="/atom.xml" title="Hexo">
  <!-- Open Graph -->
  <meta name="description" content="Templates define the presentation of your website by describing what each page should look like. The table below shows the corresponding template for every available page. At the very least, a theme s">
<meta property="og:type" content="website">
<meta property="og:title" content="Templates">
<meta property="og:url" content="https://hexo.io/docs/templates.html">
<meta property="og:site_name" content="Hexo">
<meta property="og:description" content="Templates define the presentation of your website by describing what each page should look like. The table below shows the corresponding template for every available page. At the very least, a theme s">
<meta property="og:locale" content="en">
<meta property="og:updated_time" content="2017-12-06T21:52:16.000Z">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="Templates">
<meta name="twitter:description" content="Templates define the presentation of your website by describing what each page should look like. The table below shows the corresponding template for every available page. At the very least, a theme s">
<meta name="twitter:site" content="hexojs">
<meta property="fb:admins" content="100000247608790">
  <!-- Google Analytics -->
  
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-48498357-3', 'auto');
  ga('send', 'pageview');
</script>

</head>

<body>
  <div id="container">
    <header id="header" class="wrapper">
  <div id="header-inner" class="inner">
    <h1 id="logo-wrap">
      <a href="/" id="logo">Hexo</a>
    </h1>
    <nav id="main-nav">
      <a href="/docs/" class="main-nav-link">Docs</a><a href="/api/" class="main-nav-link">API</a><a href="/news/" class="main-nav-link">News</a><a href="/plugins/" class="main-nav-link">Plugins</a><a href="/themes/" class="main-nav-link">Themes</a>
      <a href="https://github.com/hexojs/hexo" class="main-nav-link"><i class="fa fa-github-alt"></i></a>
      <div id="search-input-wrap">
        <div id="search-input-icon">
          <i class="fa fa-search"></i>
        </div>
        <input type="search" id="search-input" placeholder="Search...">
      </div>
    </nav>
    <div id="lang-select-wrap">
      <label id="lang-select-label"><i class="fa fa-globe"></i><span>English</span></label>
      <select id="lang-select" data-canonical="docs/templates.html">
        
          <option value="en" selected>English</option>
        
          <option value="zh-tw">正體中文</option>
        
          <option value="zh-cn">简体中文</option>
        
          <option value="ru">Русский</option>
        
          <option value="ko">한국어</option>
        
      </select>
    </div>
    <a id="mobile-nav-toggle">
      <span class="mobile-nav-toggle-bar"></span>
      <span class="mobile-nav-toggle-bar"></span>
      <span class="mobile-nav-toggle-bar"></span>
    </a>
  </div>
</header>

    <div id="content-wrap">
  <div id="content" class="wrapper">
    <div id="content-inner">
      <article class="article-container" itemscope itemtype="http://schema.org/Article">
        <div class="article-inner">
          <div class="article">
            <div class="inner">
              <header class="article-header">
                <h1 class="article-title" itemprop="name">Templates</h1>
                <a href="https://github.com/hexojs/site/edit/master/source/docs/templates.md" class="article-edit-link" title="Improve this doc"><i class="fa fa-pencil"></i></a>
              </header>
              <div class="article-content" itemprop="articleBody">
                <p>Templates define the presentation of your website by describing what each page should look like. The table below shows the corresponding template for every available page. At the very least, a theme should contain an <code>index</code> template.</p>
<div class="video-container"><iframe src="//www.youtube.com/embed/mb65bQ4iUc4" frameborder="0" allowfullscreen></iframe></div>
<table>
<thead>
<tr>
<th>Template</th>
<th>Page</th>
<th>Fallback</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>index</code></td>
<td>Home page</td>
<td></td>
</tr>
<tr>
<td><code>post</code></td>
<td>Posts</td>
<td><code>index</code></td>
</tr>
<tr>
<td><code>page</code></td>
<td>Pages</td>
<td><code>index</code></td>
</tr>
<tr>
<td><code>archive</code></td>
<td>Archives</td>
<td><code>index</code></td>
</tr>
<tr>
<td><code>category</code></td>
<td>Category archives</td>
<td><code>archive</code></td>
</tr>
<tr>
<td><code>tag</code></td>
<td>Tag archives</td>
<td><code>archive</code></td>
</tr>
</tbody>
</table>
<h2 id="Layouts" class="article-heading"><a href="#Layouts" class="headerlink" title="Layouts"></a>Layouts<a class="article-anchor" href="#Layouts" aria-hidden="true"></a></h2><p>When pages share a similar structure - for instance, when two templates have both a header and a footer - you can consider using a <code>layout</code> to declare these structural similarities. Every layout file should contain a <code>body</code> variable to display the contents of the template in question. For example:</p>
<figure class="highlight html"><figcaption><span>index.ejs</span></figcaption><table><tr><td class="code"><pre><span class="line">index</span><br></pre></td></tr></table></figure>
<figure class="highlight html"><figcaption><span>layout.ejs</span></figcaption><table><tr><td class="code"><pre><span class="line"><span class="meta">&lt;!DOCTYPE html&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="name">html</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="name">body</span>&gt;</span><span class="tag">&lt;<span class="name">%-</span> <span class="attr">body</span> %&gt;</span><span class="tag">&lt;/<span class="name">body</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="name">html</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>yields:</p>
<figure class="highlight html"><table><tr><td class="code"><pre><span class="line"><span class="meta">&lt;!DOCTYPE html&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="name">html</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="name">body</span>&gt;</span>index<span class="tag">&lt;/<span class="name">body</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="name">html</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>By default, the <code>layout</code> template is used by all other templates. You can specify additional layouts in the front-matter or set it to <code>false</code> to disable it. It’s even possible to build a complex nested structure by including more layout templates in your top layout.</p>
<h2 id="Partials" class="article-heading"><a href="#Partials" class="headerlink" title="Partials"></a>Partials<a class="article-anchor" href="#Partials" aria-hidden="true"></a></h2><p>Partials are useful for sharing components between your templates. Typical examples include headers, footers or sidebars. You may want to put your partials in separate files to make maintaining your website significantly more convenient. For example:</p>
<figure class="highlight html"><figcaption><span>partial/header.ejs</span></figcaption><table><tr><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="name">h1</span> <span class="attr">id</span>=<span class="string">"logo"</span>&gt;</span><span class="tag">&lt;<span class="name">%=</span> <span class="attr">config.title</span> %&gt;</span><span class="tag">&lt;/<span class="name">h1</span>&gt;</span></span><br></pre></td></tr></table></figure>
<figure class="highlight html"><figcaption><span>index.ejs</span></figcaption><table><tr><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="name">%-</span> <span class="attr">partial</span>('<span class="attr">partial</span>/<span class="attr">header</span>') %&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="name">div</span> <span class="attr">id</span>=<span class="string">"content"</span>&gt;</span>Home page<span class="tag">&lt;/<span class="name">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>yields:</p>
<figure class="highlight html"><table><tr><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="name">h1</span> <span class="attr">id</span>=<span class="string">"logo"</span>&gt;</span>My Site<span class="tag">&lt;/<span class="name">h1</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="name">div</span> <span class="attr">id</span>=<span class="string">"content"</span>&gt;</span>Home page<span class="tag">&lt;/<span class="name">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<h2 id="Local-Variables" class="article-heading"><a href="#Local-Variables" class="headerlink" title="Local Variables"></a>Local Variables<a class="article-anchor" href="#Local-Variables" aria-hidden="true"></a></h2><p>You can define local variables in templates and use them in other templates.</p>
<figure class="highlight html"><figcaption><span>partial/header.ejs</span></figcaption><table><tr><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="name">h1</span> <span class="attr">id</span>=<span class="string">"logo"</span>&gt;</span><span class="tag">&lt;<span class="name">%=</span> <span class="attr">title</span>&gt;</span><span class="tag">&lt;/<span class="name">h1</span>&gt;</span></span><br></pre></td></tr></table></figure>
<figure class="highlight html"><figcaption><span>index.ejs</span></figcaption><table><tr><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="name">%-</span> <span class="attr">partial</span>('<span class="attr">partial</span>/<span class="attr">header</span>', &#123;<span class="attr">title:</span> '<span class="attr">Hello</span> <span class="attr">World</span>'&#125;) %&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="name">div</span> <span class="attr">id</span>=<span class="string">"content"</span>&gt;</span>Home page<span class="tag">&lt;/<span class="name">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>yields:</p>
<figure class="highlight html"><table><tr><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="name">h1</span> <span class="attr">id</span>=<span class="string">"logo"</span>&gt;</span>Hello World<span class="tag">&lt;/<span class="name">h1</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="name">div</span> <span class="attr">id</span>=<span class="string">"content"</span>&gt;</span>Home page<span class="tag">&lt;/<span class="name">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<h2 id="Optimization" class="article-heading"><a href="#Optimization" class="headerlink" title="Optimization"></a>Optimization<a class="article-anchor" href="#Optimization" aria-hidden="true"></a></h2><p>If your theme is exceedingly complex or if the number of files to generate becomes too large, Hexo’s file generation performance may begin to decrease considerably. Aside from simplifying your theme, you may also try Fragment Caching, which was introduced in Hexo 2.7.</p>
<p>This feature was borrowed from <a href="http://guides.rubyonrails.org/caching_with_rails.html#fragment-caching" target="_blank" rel="noopener">Ruby on Rails</a>. It causes content to be saved as fragments and cached for when additional requests are made. This can reduce the number of database queries and can also speed up file generation.</p>
<p>Fragment caching is best used for headers, footers, sidebars or other static content that is unlikely to change from template to template. For example:</p>
<figure class="highlight js"><table><tr><td class="code"><pre><span class="line">&lt;%- fragment_cache(<span class="string">'header'</span>, <span class="function"><span class="keyword">function</span>(<span class="params"></span>)</span>&#123;</span><br><span class="line">  <span class="keyword">return</span> <span class="string">'&lt;header&gt;&lt;/header&gt;'</span>;</span><br><span class="line">&#125;);</span><br></pre></td></tr></table></figure>
<p>Though it may be easier to use partials:</p>
<figure class="highlight js"><table><tr><td class="code"><pre><span class="line">&lt;%- partial(<span class="string">'header'</span>, &#123;&#125;, &#123;<span class="attr">cache</span>: <span class="literal">true</span>&#125;);</span><br></pre></td></tr></table></figure>
<p>Don’t use fragment caching when the <code>relative_link</code> setting has been enabled. This may cause issues because relative links can and probably will be different depending on the pages they appear in.</p>

              </div>
              <footer class="article-footer">
                <time class="article-footer-updated" datetime="2017-12-06T21:52:16.000Z" itemprop="dateModified">Last updated: 2017-12-06</time>
                <a href="themes.html" class="article-footer-prev" title="Themes"><i class="fa fa-chevron-left"></i><span>Prev</span></a><a href="variables.html" class="article-footer-next" title="Variables"><span>Next</span><i class="fa fa-chevron-right"></i></a>
              </footer>
              
<section id="comments">
  <div id="disqus_thread"></div>
</section>
<script>
  var disqus_shortname = 'hexojs';
  var disqus_url = 'https://hexo.io/docs/templates.html';
  var disqus_title = "Templates";
  var disqus_config = function(){
    this.language = 'en';
  };
  (function(){
    var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
    dsq.src = 'https://go.disqus.com/embed.js';
    (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
  })();
</script>

            </div>
          </div>
          <aside id="article-toc" role="navigation">
            <div id="article-toc-inner">
              <script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=hexoio" id="_carbonads_js"></script>
              <strong class="sidebar-title">Contents</strong>
              <ol class="toc"><li class="toc-item toc-level-2"><a class="toc-link" href="#Layouts"><span class="toc-text"><a href="#Layouts" class="headerlink" title="Layouts"></a>Layouts</span></a></li><li class="toc-item toc-level-2"><a class="toc-link" href="#Partials"><span class="toc-text"><a href="#Partials" class="headerlink" title="Partials"></a>Partials</span></a></li><li class="toc-item toc-level-2"><a class="toc-link" href="#Local-Variables"><span class="toc-text"><a href="#Local-Variables" class="headerlink" title="Local Variables"></a>Local Variables</span></a></li><li class="toc-item toc-level-2"><a class="toc-link" href="#Optimization"><span class="toc-text"><a href="#Optimization" class="headerlink" title="Optimization"></a>Optimization</span></a></li></ol>
              <a href="#" id="article-toc-top">Back to Top</a>
            </div>
          </aside>
        </div>
      </article>
      <aside id="sidebar" role="navigation">
  <div class="inner">
    <strong class="sidebar-title">Getting Started</strong><a href="index.html" class="sidebar-link">Overview</a><a href="setup.html" class="sidebar-link">Setup</a><a href="configuration.html" class="sidebar-link">Configuration</a><a href="commands.html" class="sidebar-link">Commands</a><a href="migration.html" class="sidebar-link">Migration</a><strong class="sidebar-title">Basic Usage</strong><a href="writing.html" class="sidebar-link">Writing</a><a href="front-matter.html" class="sidebar-link">Front-matter</a><a href="tag-plugins.html" class="sidebar-link">Tag Plugins</a><a href="asset-folders.html" class="sidebar-link">Asset Folders</a><a href="data-files.html" class="sidebar-link">Data Files</a><a href="server.html" class="sidebar-link">Server</a><a href="generating.html" class="sidebar-link">Generating</a><a href="deployment.html" class="sidebar-link">Deployment</a><strong class="sidebar-title">Customization</strong><a href="permalinks.html" class="sidebar-link">Permalinks</a><a href="themes.html" class="sidebar-link">Themes</a><a href="templates.html" class="sidebar-link current">Templates</a><a href="variables.html" class="sidebar-link">Variables</a><a href="helpers.html" class="sidebar-link">Helpers</a><a href="internationalization.html" class="sidebar-link">Internationalization (i18n)</a><a href="plugins.html" class="sidebar-link">Plugins</a><strong class="sidebar-title">Miscellaneous</strong><a href="troubleshooting.html" class="sidebar-link">Troubleshooting</a><a href="contributing.html" class="sidebar-link">Contributing</a>
  </div>
</aside>
    </div>
  </div>
</div>

    <footer id="footer" class="wrapper">
  <div class="inner">
    <div id="footer-copyright">
      &copy; 2017 <a href="https://github.com/hexojs/hexo/graphs/contributors" target="_blank">Hexo</a><br>
      Documentation licensed under <a href="http://creativecommons.org/licenses/by/4.0/" target="_blank">CC BY 4.0</a>.
    </div>
    <div id="footer-links">
      <a href="https://twitter.com/hexojs" class="footer-link" target="_blank"><i class="fa fa-twitter"></i></a>
      <a href="https://github.com/hexojs/hexo" class="footer-link" target="_blank"><i class="fa fa-github-alt"></i></a>
    </div>
  </div>
</footer>

  </div>
  <div id="mobile-nav-dimmer"></div>
  <nav id="mobile-nav">
  <div id="mobile-nav-inner">
    <ul id="mobile-nav-list">
      <a href="/docs/" class="mobile-nav-link">Docs</a><a href="/api/" class="mobile-nav-link">API</a><a href="/news/" class="mobile-nav-link">News</a><a href="/plugins/" class="mobile-nav-link">Plugins</a><a href="/themes/" class="mobile-nav-link">Themes</a>
      <li class="mobile-nav-item">
        <a href="https://github.com/hexojs/hexo" class="mobile-nav-link" rel="external" target="_blank">GitHub</a>
      </li>
    </ul>
    
      <strong class="mobile-nav-title">Getting Started</strong><a href="index.html" class="mobile-nav-link">Overview</a><a href="setup.html" class="mobile-nav-link">Setup</a><a href="configuration.html" class="mobile-nav-link">Configuration</a><a href="commands.html" class="mobile-nav-link">Commands</a><a href="migration.html" class="mobile-nav-link">Migration</a><strong class="mobile-nav-title">Basic Usage</strong><a href="writing.html" class="mobile-nav-link">Writing</a><a href="front-matter.html" class="mobile-nav-link">Front-matter</a><a href="tag-plugins.html" class="mobile-nav-link">Tag Plugins</a><a href="asset-folders.html" class="mobile-nav-link">Asset Folders</a><a href="data-files.html" class="mobile-nav-link">Data Files</a><a href="server.html" class="mobile-nav-link">Server</a><a href="generating.html" class="mobile-nav-link">Generating</a><a href="deployment.html" class="mobile-nav-link">Deployment</a><strong class="mobile-nav-title">Customization</strong><a href="permalinks.html" class="mobile-nav-link">Permalinks</a><a href="themes.html" class="mobile-nav-link">Themes</a><a href="templates.html" class="mobile-nav-link current">Templates</a><a href="variables.html" class="mobile-nav-link">Variables</a><a href="helpers.html" class="mobile-nav-link">Helpers</a><a href="internationalization.html" class="mobile-nav-link">Internationalization (i18n)</a><a href="plugins.html" class="mobile-nav-link">Plugins</a><strong class="mobile-nav-title">Miscellaneous</strong><a href="troubleshooting.html" class="mobile-nav-link">Troubleshooting</a><a href="contributing.html" class="mobile-nav-link">Contributing</a>
    
  </div>
  <div id="mobile-lang-select-wrap">
    <span id="mobile-lang-select-label"><i class="fa fa-globe"></i><span>English</span></span>
    <select id="mobile-lang-select" data-canonical="docs/templates.html">
      
        <option value="en" selected>English</option>
      
        <option value="zh-tw">正體中文</option>
      
        <option value="zh-cn">简体中文</option>
      
        <option value="ru">Русский</option>
      
        <option value="ko">한국어</option>
      
    </select>
  </div>
</nav>
  <!-- Scripts -->
<!-- build:js build/js/main.js -->
<script src="/js/lang_select.js"></script>
<script src="/js/toc.js"></script>
<script src="/js/mobile_nav.js"></script>
<!-- endbuild -->

<!-- Algolia -->

<script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.js"></script>
<script type="text/javascript">
document.getElementById('search-input-wrap').classList.add('on');
docsearch({
  apiKey: 'c3d5d4c995b5e0c2ffb5623900279a66',
  indexName: 'hexo',
  inputSelector: '#search-input'
});
</script>


</body>
</html>